<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
    <!-- $Id: tomcat-ug.html,v 1.28 2004/02/29 22:42:50 billbarker Exp $ -->
<!--
   Copyright 1999-2004 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <link rel="stylesheet" type="text/css" href="style.css">
    <title>Tomcat User's Guide</title>
    <!-- Changed by: Costin Manolache, 20-Mar-2000 -->
    <!-- Changed by: Gal Shachor, 27-Mar-2000 -->
</head>

<body link="#0000ff" vlink="#800080">

<!-- Banner element, all hail the Project! -->

<table border="0" width="100%" cellspacing="0" cellpadding="0">
      <tr>
		<td width="50%"><a
			href="http://jakarta.apache.org/index.html"><img
			src="images/banner.gif" width="505" height="48"
			alt="The Jakarta Project" border="0"></a></td>
		<td width="50%" align="right"><img border="0" src="images/tomcat.gif" width="100" height="71" alt="The mighty Tomcat - Meow!"></td>
      </tr>
</table>
    

<H1>Tomcat 3.3 User's Guide</H1>

<p>This document is an introduction to the Tomcat 3.3 servlet
    container. It should be enough for anyone to install,
    configure and deploy Tomcat 3.3, or it's maintenance releases.
    As well, it answers many questions common to new users. If you have any
    comments or suggestions	about this document don't hesitate to send them to the
    Tomcat <a href="http://jakarta.apache.org/site/mail.html">mailing
    lists</a>.</p>
    
<p>Since Tomcat 3.3 is a reference implementation of the Servlet 2.2 and
JSP 1.1 specification, it would be very beneficial to become familiar
with these documents, to better understand much of the behavior that Tomcat
3.3 implements.  The Servlet 2.2 specification may be obtained
<a href="http://java.sun.com/products/servlet/download.html">here</a> and the
JSP 1.1 specification obtained
<a href="http://java.sun.com/products/jsp/download.html">here</a></p>

<p>One of the features of Tomcat 3.3 is its upgradability via add-on modules
(though this feature is not yet well documented). Where such an add-on module
affects Tomcat's behavior with respect to the Servlet 2.2/JSP 1.1 specifications,
Tomcat's status as a reference implementation is invalided.</p>

<p>Tomcat 3.3 can operate as a standalone web server.  In addition, it can operate
as an out-of-process servlet container for other web servers, such as Apache.
For some webservers, such as IIS, it can operate as an in-process servlet
container.  Most if this document involves information that is independent
of the mode of operation.  For details about the use of Tomcat 3.3 with other
web servers, refer to the &quot;Tomcat Documentation&quot; given below.</p>

<p>Other important documents:</p>

<ul>
	<li><a href="http://jakarta.apache.org/site/faqs.html">Jakarta FAQ Page</a></li>
	<li><A HREF="appdev/contents.html">Application Development
		manual</A> - an alternative to the User's Guide,
		somewhat out-of-date</li>
	<li>Other <a href="index.html">Tomcat Documentation</a>
		including HOWTOs for various web servers</li>
</ul>

<h2>Table of Contents</h2>

<ul>
  <li><a href="#about_tomcat">About Tomcat</a>
    <ul>
      <li><a href="#what_is_tomcat">What is Tomcat?</a></li>
      <li><a href="#where_download">Where can I download
          Tomcat?</a></li>
      <li><a href="#what_servlets_jsps">What are
          servlets? What are JSPs?</a></li>
      <li><a href="#contribute">How do/can I contribute?</a></li>
      <li><a href="#where_help">How come X, Y, or Z isn't
          working? Help!</a>
    </ul>
  </li>
  <li><a href="#using_tomcat">Using Tomcat 3.3</a>
    <ul>
      <li><a href="#install_tomcat">Installing Tomcat</a></li>
      <li><a href="#env_setup">Environment Setup</a></li>
      <li><a href="#starting_tomcat">Starting Tomcat</a></li>
      <li><a href="#stopping_tomcat">Stopping Tomcat</a></li>
      <li><a href="#tomcat_scripts">Tomcat Shell and Batch Files</a></li>
      <li><a href="#tomcat_actions">tomcat/tomcat.bat Actions</a></li>
      <li><a href="#tomcat_task_args">Tomcat Task Arguments</a></li>
    </ul>
  </li>
  <li><a href="#configuring_tomcat">Configuring Tomcat</a>
    <ul>
      <li><a href="#directory_structure">Tomcat Directory Structure</a></li>
      <li><a href="#configuring_classes">Configuring Classes</a></li>
      <li><a href="#configuring_server">Configuring the Server</a>
        <ul>
          <li><a href="#conf_svr_overview">Overview</a></li>
          <li><a href="#conf_svr_default">Default Tomcat Configuration</a></li>
          <li><a href="#conf_svr_cust">Tomcat Server.xml Customization</a></li>
          <li><a href="#standard_contexts">Tomcat's Standard Contexts</a></li>
          <li><a href="#context_addcust">Adding and Customizing Contexts</a></li>
          <li><a href="#deploy_war">Deploying WAR Files</a></li>
        </ul></li>
    </ul>
  </li>
  <li><a href="#real_world_tips">Real World Configuration Tips</a></li>
  <li><a href="#credits">Credits</a></li>
</ul>

<hr size="5">

<h2><a name="about_tomcat">About Tomcat: Q&amp;A</a></h2>

<p>See also the official <a
	href="http://jakarta.apache.org/site/faqs.html">Jakarta FAQ Page</a>.</p>

<dl>
	<dt><strong><a name="what_is_tomcat">What is Tomcat?</a></strong></dt>
	<dd>Tomcat is the official reference implementation of the <a
		href="http://java.sun.com/products/servlet/">Java
		Servlet 2.2</a> and <a
		href="http://java.sun.com/products/jsp/">JavaServer
		Pages 1.1</a> technologies. Developed under the Apache
		license in an open and participatory environment, it is
		intended to be a collaboration of the best-of-breed
		developers from around the world.</dd>

	<dt><strong><a name="where_download">Where can I download
		Tomcat?</a></strong></dt>
	<dd>At the <a
		href="http://jakarta.apache.org/site/binindex.html">Jakarta
		download page</a>!</dd>

	<dt><strong><a name="what_servlets_jsps">What are servlets? What
		are JSPs?</a></strong></dt>
	<dd>In a nutshell, servlets are memory-resident Java programs,
		running inside a servlet container (<em>e.g.,</em>
		Tomcat!). Because they're memory-resident, they can
		quickly respond to requests, as they do not incur the
		overhead of process creation and subsequent cleanup,
		unlike CGI-based scripting, e.g. perl, etc.
      
		<p>From <a href="http://java.sun.com/products/servlet/">Sun's
      servlet site</a>:</p>
    
		<blockquote>&quot;The <strong>Java<sup><font
			size="-2">TM</font></sup> Servlet API</strong>
			provides web developers with a simple,
			consistent mechanism for extending the
			functionality of a web server and for accessing
			existing business systems. A servlet can almost
			be thought of as an applet that runs on the
			server side -- without a face.&quot;</blockquote>

		<p>...and about JSPs (JavaServer Pages), again from <a
			href="http://java.sun.com/products/servlet/">Sun's
			servlet site</a>:</p>

		<blockquote>&quot;JSP technology is an extension of the
			servlet technology created to support authoring
			of HTML and XML pages. It makes it easier to
			combine fixed or static template data with
			dynamic content.&quot;</blockquote>

		<p>JSP is comparable to other technologies such as PHP
			and ASP, which combine programming/scripting
			with a markup language like HTML. The key
			difference being the programming language of
			choice. For example, PHP uses a C/C++/Java
			hybrid, ASP uses VBScript, and JSP utilizes the
			full power of the Java programming language.
			There have been many comparisons of these
			technologies, and each has its place in the
			astute developer's toolbox.</p>

		<p>All of the above information is available at <a
			href="http://java.sun.com/">Sun's Java
			website</a>, which is a starting place for all
			the ins and outs of JSPs, servlets, etc.
			<strong>Your time spent with these technologies
			will be much more rewarding if you first read
			through the <a
			href="http://java.sun.com/products/jsp/download.html">JavaServer
			Pages</a> and <a
			href="http://java.sun.com/products/servlet/download.html">servlet</a>
			specifications!</strong></p>
	</dd>
    
	<dt><strong><a name="contribute">How do/can I contribute?</a></strong></dt>
	<dd>Please do! See the Jakarta project contribution page, right
		<a
		href="http://jakarta.apache.org/site/getinvolved.html">here</a>.
		You'll probably want to <a
		href="mailto:tomcat-dev-subscribe@jakarta.apache.org">subscribe</a>
		to the <strong>tomcat-dev</strong> mailing list.</dd>

	<dt><strong><a name="where_help">How come X, Y, or Z isn't
		working? Help!</a></strong></dt>
	<dd>While we hope to cater to many common issues, we have
		undoubtedly missed some. For more help, try (in this
		order):

<ol>
	<li>Your log files, in the <a href="#logs_dir_defn">logs</a>
		subdirectory of your Tomcat installation. These are an
		untapped resource!</li>      
	<li>Have a look through the <a
		href="http://jakarta.apache.org/site/faqs.html">
		Jakarta FAQ Page</a>. Most installation and configuration
		questions can be found here.</li>      
	<li>Search the Tomcat User List archive
        <a href="http://www.mail-archive.com/tomcat-user@jakarta.apache.org/">here</a>
        or <a href="http://mikal.org/interests/java/tomcat/index.html">here</a>
		and the Tomcat Developer List archive
        <a href="http://www.mail-archive.com/tomcat-dev@jakarta.apache.org/">here</a>
        or <a href="http://www.metronet.com/~wjm/tomcat/">here</a>.</li>
	<li>Post a question to the <strong> tomcat-user</strong> <a
		href="http://jakarta.apache.org/site/mail.html">
		mailing list</a>, to which you must first <a
		href="mailto:tomcat-user-subscribe@jakarta.apache.org">subscribe</a>
		before posting your question.</li>
</ol>

	</dd>
</dl>

<hr size="5">

<h2><a name="using_tomcat">Using Tomcat 3.3</a></h2>

<p>A lot of effort has been put into making Tomcat easy to use as well as flexible.
It comes with a default configuration which should be a good starting point
for most users.  Once you have Tomcat 3.3 up and running, there are many
customizations from which you can choose.</p>

<p>To help identify which version of Tomcat you have, a &quot;version&quot;
name has been incorporated in a number of places.  It is in the name of
the binary and source archives as well as the directory to which the archives
expand. <i>&lt;version&gt;</i> will appear in the text below where this
&quot;version&quot; name appears. The version will be &quot;3.3&quot; for the
initial Tomcat 3.3 release, and &quot;3.3.<i>x</i>&quot; for subsequent
maintenance releases.</p>

<h3><a name="install_tomcat">Installing Tomcat</a></h3>

<p>This section deals with installing the Tomcat 3.3 binary archive available
from the Jakarta Project.  It is also possible to install Tomcat 3.3 by
building it from source, but that isn't covered in this document.</p>

<ul>
  <li><a href="http://jakarta.apache.org/site/binindex.html">Download</a> the
    appropriate jakarta-tomcat-<i>&lt;version&gt;</i> binary archive file. For
    Linux, RPMs are available.<br><br></li>

  <li>Expand the archive into some directory (say /usr/local or C:\). This
      should create a new subdirectory named
      <code>&quot;jakarta-tomcat-<i>&lt;version&gt;</i>&quot;</code>. You may
      rename this directory if you wish.  Just remember to adjust
      the instructions that follow to use the new name.  If you are using
      Linux, RPMs may be installed with the command &quot;rpm -Uvh&quot;. Type
      <strong>man rpm</strong> for more info.</li>
</ul>

<h3><a name="env_setup">Environment Setup</a></h3>

<p>There are a number of different methods to start and stop Tomcat 3.3. There
are differences in the environmental setup needed for these methods. This
section addresses the environmental setup needed for using the shell scripts
and batch files provided to simplify starting and stopping Tomcat.  This
section also assumes you will be manually starting and stopping Tomcat from
a shell or MS-DOS window.</p>
      
<ul>
  <li>In a shell or DOS window, change to the
      <code>&quot;jakarta-tomcat-<i>&lt;version&gt;</i>&quot;</code> directory.<br><br></li>

  <li>Set the environment variable JAVA_HOME to point to the root
      directory of your JDK hierarchy.  You may optionally add the Java
      interpreter to your PATH environment variable. The exact directory
      may vary from system to system. Check your local file system to be sure
      where Java is installed.
      <br><br>
	<ol>
  	<li>Win32:<br>
      	<tt><big>
      	set JAVA_HOME=c:/jdk1.3.1<br>
      	set PATH=%JAVA_HOME%\bin;%PATH%
      	</big></tt>
      	</li>
  	<li>Unix (bash/sh):<br>
      	<tt><big>
      	JAVA_HOME=/usr/local/java/jdk1.3.1; export JAVA_HOME<br>
      	PATH=$JAVA_HOME/bin:$PATH; export PATH<br>
      	</big></tt>
      	</li>
  	<li>Unix (tcsh):<br>
      	<tt><big>
      	setenv JAVA_HOME=/usr/local/java/jdk1.3.1<br>
      	setenv PATH $JAVA_HOME/bin:$PATH<br>
      	</big></tt>
      	</li>
	</ol><br><br></li>

  <li>You may optionally set the TOMCAT_HOME environment variable.  If
      the supplied shell/batch scripts are executed from
      <tt>&quot;jakarta-tomcat-<i>&lt;version&gt;</i>&quot;</tt> or from
      its &quot;bin&quot; subdirectory, then they will successfully set
      TOMCAT_HOME for you if not already set.  If you wish to execute
      these shell/batch scripts from other directories, you must set
      TOMCAT_HOME explicitly.
      <br><br>
    <ol>
      <li>On Win32 systems you should type: <br>
          <tt><big>set TOMCAT_HOME=c:\jakarta-tomcat-<i>&lt;version&gt;</i>
          </big></tt></li>
      <li>On UNIX (using bash/sh) you should type: <br>
          <tt><big>TOMCAT_HOME=/usr/local/jakarta-tomcat-<i>&lt;version&gt;</i> ; export TOMCAT_HOME
          </big></tt></li>
      <li>On UNIX (using tcsh) you should type: <br>
          <tt><big>setenv TOMCAT_HOME /usr/local/jakarta-tomcat-<i>&lt;version&gt;</i>
          </big></tt></li>
    </ol><br><br></li>
    
  <li><a name="out_of_env"></a>If you are using Win9x, you will need to deal
      with the potential <b>&quot;Out of environment space&quot;</b> problem, if you
      haven't already. In the standard installation of Win9x, the default
      amount of environment space provided to MS-DOS windows is too small for
      Tomcat's batch files to run.  There are several ways to increase the
      size of the environment space.
      <br><br>      
    <ol>
      <li>A global solution is to add a &quot;SHELL&quot; command to your
          <code>CONFIG.SYS</code> file.  Click Start -&gt; Run and
          enter <code>sysedit</code>.  Then click OK.  In the
          <code>C:\CONFIG.SYS</code> window, add the line:
          <pre>SHELL=C:\COMMAND.COM /E:4096 /P</pre>
          and click File -&gt; Save.  Then click File -> Exit and
          reboot your system. The default amount of environment space will
          now be 4096 bytes, more than enough for Tomcat.</li>
      <li>If you plan on always starting Tomcat 3.3 from the
          &quot;MS-DOS Prompt&quot;, open a &quot;MS-DOS Prompt&quot;.
          Right click on the icon in the upper left corner of the DOS
          window and select Properties.  In this dialog, select the Memory
          tab and change the &quot;Initial environment:&quot; setting
          to 4096.  Click OK and close the MS-DOS window. Now, whenever you
          open an &quot;MS-DOS Prompt&quot;, you will have enough environment
          space to start and stop Tomcat.</li>
      <li>If you like double-clicking files in Windows Explorer to run them,
          you can execute <code>sysedit</code> as described in the first
          method and add the <code>&quot;set JAVA_HOME ...&quot;</code> line
          from above to the <code>AUTOEXEC.BAT</code> file.  Next in Windows
          Explorer, navigate to Tomcat's <code>bin</code> directory.  Right
          click on the <code>startup.bat</code> file and select Properties.
          Set the &quot;Initial environment:&quot; as described in the second
          method. Also select the Program tab and check the &quot;Close on
          exit&quot; option. Repeat this procedure for the <code>shutdown.bat</code>
          file. Reboot the system so the change to the <code>AUTOEXEC.BAT</code>
          file can take effect.  Now you should be able to double-click
          on the <code>startup.bat</code> and <code>shutdown.bat</code> files
          in Windows Explorer to start and stop Tomcat.</li>
    </ol></li>
</ul>

<p>Once you're sure they work, you may wish to set the environment
variables in a configuration file: C:/AUTOEXEC.BAT for Windows, ~/.bash_profile
or ~/.cshrc, etc.  Alternatively, you could customize Tomcat's script or
batch files to incorporate the environment settings.</p>
	  
<h3><a name="starting_tomcat">Starting Tomcat</a></h3>

<p>Assuming you have opened a shell or MS-DOS window and set the environment
as described in the prior section, you are now ready to start and later
stop Tomcat 3.3.</p>

<p>To start Tomcat 3.3, execute:</p>

<ul>
  <li>On UNIX: bin/startup</li>
  <li>On Win32: bin\startup</li>
</ul>

<p>This will start Tomcat 3.3 in the background on Unix based systems, or in
a new MS-DOS window on Windows based systems.  If you are using Win9x, and
you see &quot;Out of environment space&quot;, double check your setup for
the last item in the prior section.</p>

<p>You will need to wait a short period of time before Tomcat 3.3 is ready
to serve requests. The very first use will need a little extra time since
some WAR files will be expanded by default.</p>

<p>You can tell when Tomcat 3.3 has completed its startup when text like the
following appears in the log output.</p>
<pre>
2001-09-01 14:23:30 - Http10Interceptor: Starting on 8080
2001-09-01 14:23:30 - Ajp12Interceptor: Starting on 8007
2001-09-01 14:23:30 - Ajp13Interceptor: Starting on 8009
</pre>

<p>In Tomcat's default configuration, Tomcat's output log is not assigned to
a file.  Instead, Tomcat's log output goes <code>stderr</code>.  On Windows
systems, you can switch to the MS-DOS window to see if this test has
appeared.</p>

<p>As you might guess from the above log text, the default Tomcat 3.3 configuration
will service HTTP requests on port 8080.  If you start your browser and open
<a href="http://localhost:8080/">http://localhost:8080/</a> you will see Tomcat
3.3's Welcome page.</p>

<p>In addition to serving HTTP, the default configuration will service Ajp12
protocol requests on port 8007 and Ajp13 protocol requests on 8009. These
protocols are used by the &quot;connectors&quot; which allow Tomcat to be used
as a Servlet/JSP container for an external web server, such as Apache. Also,
the Ajp12 protocol is used by the Tomcat shutdown process.</p>

<p>Though documented below, here are a couple of items that you may find
useful.</p>

<ul>
  <li>You may pass options and system property settings to the Java VM by
      specifying them in an environment variable called TOMCAT_OPTS (for
      instance: '-server' is useful as a performance enhancement if you're
      running Sun's HotSpot VM).<br>
      <b>Note:</b> On Win9x, you will not be able so include system property
      settings in TOMCAT_OPTS because the <code>SET</code> command won't
      accept a line with more than one equals sign.</li>
  <li>The &quot;auto-generated&quot; configuration files for external web
      servers, such as Apache, are not written during a normal startup of
      Tomcat.  To write the configuration files, append <code>jkconf</code>
      to the startup command. Tomcat will initialize sufficiently to write
      the files and then exit.  This may be done while the Tomcat 3.3 is
      running as a web server. </li>
</ul>

<h3><a name="stopping_tomcat">Stopping Tomcat</a></h3>

<p>To perform a normal shutdown of Tomcat 3.3, a special &quot;shutdown&quot;
request must be send from a separate process, or possibly a different computer.
In the default configuration, that &quot;shutdown&quot; request must be made
using the Ajp12 protocol. If the shell or MS-DOS window used to start Tomcat
is not still open, first open a new one and set the environment the same as for
starting Tomcat.</p>

<p>To stop Tomcat 3.3, execute:</p>

<ul>
  <li>On UNIX: bin/shutdown</li>
  <li>On Win32: bin\shutdown</li>
</ul>

<p>The shutdown process incorporates a <code>host</code>, <code>port</code>,
and a <code>password</code>. In the default configuration, the <code>host</code>
defaults to <code>localhost</code>. This means that Tomcat 3.3 can only be
shutdown from the same computer that started it.  The <code>port</code>
automatically defaults to the port being used by the Ajp12 protocol. The
<code>password</code> defaults to &quot;not specified&quot;. This means that
a password will not be required to shutdown Tomcat 3.3.</p>
  
<h3><a name="tomcat_scripts">Tomcat Shell and Batch Files</a></h3>

<p>Tomcat's shell and batch files are found in Tomcat's <code>bin</code>
directory. These files support &quot;actions&quot; beyond starting and
stopping Tomcat. To help make better use of the functionality provided, the
following table describes each of these files. If desired, you can customize
these batch files to suit your needs.</p>

<h4>Tomcat Shell and Batch files</h4>
<table border="1">
  <tr><th bgcolor="#c0c0c0">File</th><th bgcolor="#c0c0c0">Description</th></tr>
  <tr><td>cpappend.bat</td><td>This batch file is used by <code>tomcat.bat</code>
    to build a classpath in a couple of <code>tomcat.bat</code>'s other
    functions.  It is not executed during Tomcat start and stop functions.</td></tr>
  <tr><td>jspc</td><td>Shell script to invoke JSPC on Unix based systems. It
    uses <code>tomcat</code> with the &quot;jspc&quot; option to pre-translate
    JSP pages to Java files.</td></tr>
  <tr><td>jspc.bat</td><td>Batch file to invoke JSPC on Windows based systems.
    It uses <code>tomcat.bat</code> with the &quot;jspc&quot; option to
    pre-translate JSP pages to Java files.</td></tr>
  <tr><td>shutdown.bat</td><td>Batch file for stopping Tomcat on Windows based
    systems. If TOMCAT_HOME is not set, it should be executed from Tomcat's home
    directory, or one of its subdirectories. It executes <code>tomcat.bat</code>
    with the &quot;start&quot; argument. Features and limitations of
    <code>tomcat.bat</code> apply to this batch file.</td></tr>
  <tr><td>shutdown</td><td>Shell script for stopping Tomcat on Unix based
    systems.  It executes <code>tomcat</code> with the &quot;stop&quot;
     argument. Features and limitations of <code>tomcat</code> apply to
     this script.</td></tr>
  <tr><td>tomcat</td><td>The main script for Unix based systems. It can start
    and stop Tomcat, as well as perform other functions.  It makes a number of
    attempts to guess TOMCAT_HOME if not set explicitly (see script contents
    for details). It can also guess your JAVA_HOME if it is in your PATH
    environment variable.</td></tr>
  <tr><td>startup.bat</td><td>Batch file for starting Tomcat on Windows based
    systems. If TOMCAT_HOME is not set, it should be executed from Tomcat's home
    directory, or one of its subdirectories. It executes <code>tomcat.bat</code>
    with the &quot;start&quot; argument. Features and limitations of
    <code>tomcat.bat</code> apply to this batch file.</td></tr>
  <tr><td>startup</td><td>Shell script for starting Tomcat on Unix based
     systems. It executes <code>tomcat</code> with the &quot;start&quot;
     argument. Features and limitations of <code>tomcat</code> apply to
     this script.</td></tr>
  <tr><td>tomcat.bat</td><td>The main batch file for Windows based systems. It
    can start and stop Tomcat, as well as perform other functions.  It can guess
    TOMCAT_HOME if it isn't set explicitly, provided this batch file is executed
    from Tomcat's home directory or one of its subdirectories. JAVA_HOME must
    be set for this batch file to function.  An error message is displayed if
    not set.</td></tr>
  <tr><td>tomcatEnv.bat</td><td>A batch file that executes <code>tomcat.bat</code>
    with the &quot;env&quot; option to set Tomcat's runtime environment in your
    MS-DOS window.</td></tr>
</table>

<p>You may have noted that <code>tomcat</code> and <code>tomcat.bat</code>
are the primary scripts. They are the scripts that actually perform the
&quot;actions&quot;. The list of actions, as well as additional environment
variables they support, are described in the
<a href="#tomcat_actions">next section</a>.</p>

<p>Note that most actions involve starting the
<code>org.apache.tomcat.startup.Main</code> class in a Java VM. This class
and some classes it uses also accept arguments. To take advantage of the
full capabilities of Tomcat, you will need to become familiar with these
arguments as well. See <a href="#tomcat_task_args">Tomcat Task Arguments</a>
for those details.</p>

<h3><a name="tomcat_actions">tomcat/tomcat.bat Actions</a></h3>

<p>The <code>tomcat</code> shell script and <code>tomcat.bat</code> batch
files contain the code that invokes the various features of Tomcat 3.3.  It
supports a number of actions specified by the first argument.  The following
table lists the supported actions. Almost all of the actions involve starting
a Java VM.  An environment variable, TOMCAT_OPTS or JSPC_OPTS, is provided for
specifying Java VM options, such as &quot;-Xmx256m&quot; and system property
settings, such as &quot;-Dmy.prop=myvalue&quot;. The <code>jspc</code> action
uses the <code>JSPC_OPTS</code> environment variable.  All other actions with
support this environment variable use <code>TOMCAT_OPTS</code>.</p>

<p><b>Note:</b> On Win9x, you will not be able to include system property
settings in <code>TOMCAT_OPTS</code> or <code>JSPC_OPTS</code> because the
<code>SET</code> command will not accept a line with more than one equals
sign. If you need an additional system property setting, you will need to
modify your <code>tomcat.bat</code> to include it on the command line.</p>

<h4>Actions supported by the tomcat and tomcat.bat scripts</h4>
<table border="1">
  <tr><th bgcolor="#c0c0c0">Action</th><th bgcolor="#c0c0c0">Description</th></tr>
  <tr><td>start</td><td>This action starts up Tomcat in the background on Unix
    based systems, and in a new MS-DOS window on Windows based systems.
    Java VM options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
  <tr><td>stop</td><td>This actions tries to stop the running Tomcat. Java VM
    options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
  <tr><td>run</td><td>This action starts up Tomcat in the foreground on Unix
    based systems, and in the current MS-DOS window on Windows based systems.
    Java VM options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
  <tr><td>enableAdmin</td><td>Rewrites the <code>apps-admin.xml</code> file in
    Tomcat's <code>conf</code> directory so that the admin web application is
    &quot;trusted&quot;.  For security reasons, the admin web application is
    &quot;untrusted&quot; by default. If you plan to leave the admin web
    application trusted, you should change the admin password found in the
    <code>admin-users.xml</code> file in the <code>conf/users</code> directory.
    Java VM options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
  <tr><td>env</td><td>Sets the TOMCAT_HOME and CLASSPATH environment variables
    to match Tomcat's runtime environment.  This is useful for compiling
    servlets or other Java files for use within Tomcat. For best results, ensure
    TOMCAT_HOME is set to an absolute path.  If set to &quot;.&quot;
    or &quot;..&quot;, the CLASSPATH environment variable will be invalid if
    you leave the current directory.</td></tr>
  <tr><td>jspc</td><td>Pre-translates specified JSP pages to Java files.
    Java VM options may be specified in the JSPC_OPTS environment variable.</td></tr>
  <tr><td>estart</td><td>Starts Tomcat without reading the server.xml file.
    Instead, the set of modules making up the instance of Tomcat is created
    internally by org.apache.tomcat.startup.EmbededTomcat. This command is
    useful for testing customized versions of the EmbededTomcat class when
    trying to embed Tomcat in an application. Java VM options may be specified
    in the TOMCAT_OPTS environment variable.</td></tr>
</table>

<p>Except for the <code>env</code> action, each action corresponds to a
&quot;task&quot; supported by the <code>org.apache.tomcat.startup.Main</code>
class. The <code>tomcat</code> and <code>tomcat.bat</code> files, as well
as the files that call them, will pass additional arguments on the command line
to the <code>Main</code> class as arguments. See the next section for what
arguments are supported by each of the tasks.</p>

<p>Also note that the TOMCAT_HOME environment variable is passed to the
startup class via a <code>tomcat.home</code> system property.</p>

<h3><a name="tomcat_task_args">Tomcat Task Arguments</a></h3>

<p>The <code>org.apache.tomcat.startup.Main</code> class is the primary class
used for executing a Tomcat &quot;task&quot;, i.e. start, stop, etc. The term
&quot;task&quot; is used instead of &quot;action&quot; because it is more than
just an argument here. Each task has an associated class which will be executed
to perform the task. The first argument passed to the <code>main()</code>
method of <code>org.apache.tomcat.startup.Main</code> will determine which
&quot;task&quot; class gets executed. Each of the &quot;task&quot; classes
supports its own set of arguments.  These arguments are documented in the
table that follows.</p>

<p><b>Note:</b> The arguments to each of the tasks may be optionally preceded
by a '-'. However, the &quot;task&quot; argument must not be preceded by a '-'.
If you specified <code>-stop</code> as the task, the default &quot;start&quot;
task would be executed and <code>-stop</code> passed to the &quot;start&quot;
task as an argument.</p>

<h4>Tasks supported by org.apache.tomcat.startup.Main</h4>
<table border="1">
  <tr><th bgcolor="#c0c0c0">Task</th><th bgcolor="#c0c0c0">Argument</th>
    <th bgcolor="#c0c0c0">Description</th></tr>
  <tr><td>start<br>run<br>estart</td><td>&nbsp;</td>
    <td>Starts Tomcat using the org.apache.tomcat.startup.EmbededTomcat class.
	  This is the default action.</td></tr>
  <tr><td>&nbsp;</td><td>config&nbsp;<i>&lt;file&gt;</i><br>
      or<br>f&nbsp;<i>&lt;file&gt;</i></td>
    <td>Use specified server configuration file instead of the default
    <code>server.xml</code>.</td></tr>
  <tr><td>&nbsp;</td><td>debug <i>&lt;level&gt;</i></td>
    <td>Set the debug level for the ContextManager.</td></tr>
  <tr><td>&nbsp;</td><td>estart</td>
    <td>Starts Tomcat without reading the server.xml file. Instead, the Tomcat
	  instance is constructed internally by this class.</td></tr>
  <tr><td>&nbsp;</td><td>help</td><td>Display usage information.</td></tr>
  <tr><td>&nbsp;</td><td>home&nbsp;<i>&lt;dir&gt;</i><br>
      or<br>h&nbsp;<i>&lt;dir&gt;</i></td>
    <td>Use specified directory as Tomcat's home directory, i.e. the directory
      under which the <code>conf</code>, <code>webapps</code>, <code>logs</code>,
      and <code>work</code> directories are found.</td></tr>
  <tr><td>&nbsp;</td><td><span>install&nbsp;<i>&lt;dir&gt;</i></span><br>
      or<br>i&nbsp;<i>&lt;dir&gt;</i></td>
    <td>Use specified directory as Tomcat's install director, i.e. where the
      <code>lib</code> directory is found.</td></tr>
  <tr><td>&nbsp;</td><td>sandbox</td>
    <td>Run Tomcat with a security manager.</td></tr>
  <tr><td>&nbsp;</td><td>jkconf</td>
    <td>Generate configuration files instead of starting Tomcat.</td></tr>

  <tr><td>stop</td><td>&nbsp;</td>
    <td>Stops Tomcat using the org.apache.tomcat.startup.StopTomcat class.</td></tr>
  <tr><td>&nbsp;</td><td>ajpid&nbsp;<i>&lt;file&gt;</i><br>
      or<br>secretFile&nbsp;<i>&lt;file&gt;</i></td>
    <td>Specify the defaults file written by the
      <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a> or
      <a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> module. It
      contains default values for <code>port</code>, <code>host</code>, and
      <code>pass</code> arguments.  The default value is
      <code>TOMCAT_HOME/conf/ajp12.id</code> or <code>TOMCAT_HOME/conf/ajp13.id</code>
      if <code>ajp12</code> or <code>ajp13</code> is specified, respectively.
      If neither <code>ajp12</code> or <code>ajp13</code> is specified, the
      ajpid file defaults first to <code>TOMCAT_HOME/conf/ajp13.id</code>, and
      if not found, defaults to <code>TOMCAT_HOME/conf/ajp12.id</code>.</td></tr>
  <tr><td>&nbsp;</td><td>ajp12</td><td>Specifies that the ajp12 protocol should
      be used for shutdown. It implies the format of the ajpid file as that
      written by the Ajp12Connector.</td></tr>
  <tr><td>&nbsp;</td><td>ajp13</td><td>Specifies that the ajp13 protocol should
      be used for shutdown. It implies the format of the ajpid file as that
      written by the Ajp13Connector.</td></tr>
  <tr><td>&nbsp;</td><td>ajpid12&nbsp;<i>&lt;file&gt;</i><br><b>[Tomcat 3.3.1]</b></td>
    <td>Equivalent to specifying <code>ajpid&nbsp;<i>&lt;file&gt;</i></code>
      and <code>ajp12</code>.</td></tr>
  <tr><td>&nbsp;</td><td>ajpid13&nbsp;<i>&lt;file&gt;</i><br><b>[Tomcat 3.3.1]</b></td>
    <td>Equivalent to specifying <code>ajpid&nbsp;<i>&lt;file&gt;</i></code>
      and <code>ajp13</code>.</td></tr>
  <tr><td>&nbsp;</td><td>help</td><td>Display usage information.</td></tr>
  <tr><td>&nbsp;</td><td>home&nbsp;<i>&lt;dir&gt;</i><br>
      or<br>h&nbsp;<i>&lt;dir&gt;</i></td>
    <td>Use specified directory as Tomcat's home directory, i.e. the directory
      under which the <code>conf</code> directory is found.</td></tr>
  <tr><td>&nbsp;</td><td>host&nbsp;<i>&lt;host&gt;</i></td>
    <td>The host running the Tomcat instance you wish to shutdown. Defaults to
      value in defaults file if available.  Otherwise it defaults to the local
      system.</td></tr>
  <tr><td>&nbsp;</td><td>port&nbsp;<i>&lt;port&gt;</i></td>
    <td>The port of the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
      in the Tomcat instance you wish to shutdown.  Must be specified if
      a default value can not be read from the defaults file.</td></tr>
  <tr><td>&nbsp;</td><td>pass&nbsp;<i>&lt;string&gt;</i><br>
      or<br>secret <i>&lt;string&gt;</i></td>
    <td>The &quot;secret&quot; password string expected by the
      <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a> for a shutdown
      request. The Ajp12Connector defaults to not using a &quot;secret&quot;
      string, in which case this argument may be omitted.  If the
      Ajp12Connector is using a &quot;secret&quot; string, you must specify
      the same string if the default can not be read from the defaults file or
      the shutdown will fail.</td></tr>

  <tr><td>enableAdmin</td><td>&nbsp;</td>
    <td>Rewrites the TOMCAT_HOME/conf/apps-admin.xml context configuration file
	  using the org.apache.tomcat.startup.EnableAdmin class.</td></tr>
  <tr><td>&nbsp;</td><td>home&nbsp;<i>&lt;dir&gt;</i><br>
      or<br>h&nbsp;<i>&lt;dir&gt;</i></td>
    <td>Use specified directory as Tomcat's home directory, i.e. the directory
      under which the <code>conf/apps-admin.xml</code> file is found.</td></tr>
  <tr><td>jspc</td><td>&nbsp;</td>
    <td>Pre-compiles JSP pages using the org.apache.tomcat.startup.Jspc class.</td></tr>
  <tr><td>&nbsp;</td><td>&nbsp;</td><td><i>arguments not yet documented</i></td></tr>
</table>

<p>The <code>start</code>, <code>run</code>, and <code>estart</code> tasks
assume a command line argument that doesn't match one of the predefined
arguments is a ContextManager property name and the next command line argument
is its value.  Thus a command such as:</p>

<pre>bin/startup myprop myvalue</pre>

<p>would define a ContextManager property named &quot;myprop&quot; with a
String value of &quot;myvalue&quot;.  ContextManager properties can used for
parameter substitution in the <code>server.xml</code> file.  Set the
<a href="serverxml.html#substitution">Variable substitution</a> section of
the Server.xml document for details.  There are also some ContextManager
properties supported by certain modules.  These are listed in the following
table.</p>

<table border="1">
  <tr><th bgcolor="#c0c0c0">Module</th>
    <th bgcolor="#c0c0c0">Context Property</th>
    <th bgcolor="#c0c0c0">Description</th></tr>
  <tr><td><a href="serverxml.html#Ajp12Connector">Ajp12Connector</a></td>
    <td>ajpid12</td>
    <td>Overrides the <code>ajpidFile</code> attribute to specify the file
      in which to record Ajp12 connector info and password.</td></tr>
  <tr><td><a href="serverxml.html#Ajp13Connector">Ajp13Connector</a></td>
    <td>ajpid13</td>
    <td>Overrides the <code>ajpidFile</code> attribute to specify the file
      in which to record Ajp13 connector info and password.</td></tr>
  <tr><td><a href="serverxml.html#LoaderInterceptor11">LoaderInterceptor11</a></td>
    <td>additionalJars</td>
    <td>List of jars to be added to each web application.</td></tr>
</table>

<p></p>

<hr size="5">

<h2><a name="configuring_tomcat">Configuring Tomcat 3.3 </a></h2>

<p>Customizing Tomcat will involve adding or modifying one or more files
involved with Tomcat. The next section describes the
<a href="#directory_structure">directory structure</a> of Tomcat 3.3 to document
where files are found. Following that are sections document the two parts to
Tomcat configuration.</p>

<ul>
  <li><a href="#configuring_classes">Configuring classes</a></li>
  <li><a href="#configuring_server">Configuring the server</a></li>
</ul>

<h3><a name="directory_structure">Tomcat Directory Structure</a></h3>

<p>After installing Tomcat 3.3, you should have the following directory
structure under <code>&quot;jakarta-tomcat-<i>&lt;version&gt;</i>&quot;</code>.
Customization of Tomcat 3.3 will involve adding or modifying files in one
or more of these directories.</p>

<table border=1 width="75%" valign="center">
  <tr>
    <th bgcolor="#c0c0c0" WIDTH="15%">Directory</th>
    <th bgcolor="#c0c0c0" WIDTH="85%">Contents</th>
  </tr>
  <tr>
    <td WIDTH="15%" align="left">bin</td>
    <td WIDTH="85%"> Startup/shutdown scripts and other useful files.</td>
  </tr>
  <tr>
    <td WIDTH="15%" align="left">conf</td>
    <td WIDTH="85%"> <a href="#configuring_server">Configuration files</a>,
      including  modules.xml, server.xml, and a number of apps-<i>&lt;name&gt;</i>.xml.</td>
  </tr>
  <tr>
    <td width="15%" align="left">conf/auto</td>
    <td width="85%">Directory where auto-generated configuration files are
      written.</td>
  </tr>
  <tr>
    <td width="15%" align="left">conf/jk</td>
    <td width="85%">Directory containing mod_jk specific configuration files.</td>
  </tr>
  <tr>
    <td width="15%" align="left">conf/jserv</td>
    <td width="85%">Directory containing mod_jserv specific configuration files.</td>
  </tr>
  <tr>
    <td width="15%" align="left">conf/users</td>
    <td width="85%">Directory containing user name/password configuration files.
      These are used by the SimpleRealm module for authentication.</td>
  </tr>
  <tr>
    <td WIDTH="15%" align="left">doc</td>
    <td WIDTH="85%">Miscellaneous documents regarding Tomcat.</td>
  </tr>
  <tr>
    <td WIDTH="15%" align="left">lib</td>
    <td WIDTH="85%">Jar files that are used for starting and stopping Tomcat.</td>
  </tr>
  <tr>
    <td width="15%" align="left">lib/container</td>
    <td width="85%">Jar files that make up the Tomcat server classes.  Any
      Jar file in this directory is automatically included in Tomcat's
      <b>Server Classloader</b>.  See 
      <a href="#configuring_classes">Configuring Classes</a>.</td>
  </tr>
  <tr>
    <td width="15%" align="left">lib/common</td>
    <td width="85%">Jar files that contain classes shared between the Tomcat
      server and all web applications. Any Jar file in this directory is
      automatically included in Tomcat's <b>Common Classloader</b>.  See 
      <a href="#configuring_classes">Configuring Classes</a>.</td>
  </tr>
  <tr>
      <td width="15%" align="left">lib/apps</td>
      <td width="85%">Jar files that contain classes shared between all web
        applications. Any Jar file in this directory is automatically included
        in Tomcat's <b>Apps Classloader</b>.  See 
        <a href="#configuring_classes">Configuring Classes</a>.</td>
  </tr>        
  <tr>
    <td WIDTH="15%" align="left"><a name="logs_dir_defn">logs</a></td>
    <td WIDTH="85%"> This is where Tomcat places its log files by default.</td>
  </tr>
  <tr>
    <td width="15%" align="left">modules</td>
    <td width="85%">Directory where &quot;add-on&quot; WARs are placed.</td>
  </tr>
  <tr>
    <td width="15%" align="left">native</td>
    <td width="85%">Base directory for native source code.</td>
  </tr>
  <tr>
    <td WIDTH="15%" align="left">src</td>
    <td WIDTH="85%">Currently empty.  Tomcat's source code isn't currently
     part of the binary distribution.</td>
  </tr>
  <tr>
    <td WIDTH="15%" align="left">webapps</td>
    <td WIDTH="85%"> Sample web applications. Any .war files placed
      here will be automatically expanded.  See <a href="#deploy_war">Deploying WAR Files</a>.</td>
  </tr>
</table>

<p>Additionally you can, or Tomcat will, create the following
directories:</p>

<table border="1" width="75%" VALIGN="center">
  <tr>
    <td width="15%" align="left"> <a name="work_dir_defn"> work</a></td>
    <td width="85%"> Where Tomcat
         places intermediate files (such as compiled JSP files) during 
         its work. If you delete this directory while Tomcat is running 
         you will not be able to execute JSP pages.
    </td>
  </tr>
  <tr>
    <td width="15%" align="left">classes</td>
    <td width="85%"> Any class that you add to this directory will 
         find its place in Tomcat's classpath.
    </td>
  </tr>
</table>

<h3><a name="configuring_classes">Configuring Classes</a></h3>

<p>Configuring classes refers to configuring what classes are available and the
scope of their availability when Tomcat 3.3 is running.  You may wish to add
additional classes and jars.  Also, a web application may need some modification
based on what Tomcat 3.3 makes available by default.</p>

<p>The available classes are determined by the classloader hierarchy that
Tomcat 3.3 creates when it starts up.  The classloader hierarchy built by
Tomcat 3.3 looks like this:</p>

<table align="center" class="cltable" border="0" cellspacing="0">
  <tr><td>
    <table align="center">
      <tr><td class="clt_loader">Server Classloader</td></tr>
      <tr><td class="clt_label">directory:</td></tr>
      <tr><td class="clt_data">lib/container</td></tr>
      <tr><td class="clt_label">default contents:</td></tr>
      <tr>
        <td class="clt_data">crimson.jar<br>facade22.jar<br>
          jasper.jar<br>tomcat_modules.jar<br>tomcat_util.jar<br>xalan.jar<br>
          (if RPM)commons-collections.jar<br>commons-dbcp.jar<br>
          commons-pool.jar<br></td></tr>
    </table></td>
	<td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>
    <table align="center">
      <tr><td class="clt_loader">Webapp Classloader(s)</td></tr>
      <tr><td class="clt_label">directory:</td></tr>
      <tr><td class="clt_data">WEB-INF/classes<br>WEB-INF/lib</td></tr>
	  <tr><td align="center">|</td></tr>
      <tr><td class="clt_loader">Apps Classloader</td></tr>
      <tr><td class="clt_label">directory:</td></tr>
      <tr><td class="clt_data">lib/apps</td></tr>
      <tr><td class="clt_label">default contents:</td></tr>
      <tr><td class="clt_data"><i>empty</i></td></tr>
	  </table>
	</td></tr>
  <tr><td>&nbsp;</td><td align="center">\</td><td>&nbsp;</td><td align="center">/</td><td>&nbsp;</td></tr>
  <tr><td>&nbsp;</td><td>&nbsp;</td><td>
    <table align="center">
      <tr><td class="clt_loader">Common Classloader</td></tr>
      <tr><td class="clt_label">directory:</td></tr>
      <tr><td class="clt_data">lib/common</td></tr>
      <tr><td class="clt_label">default contents:</td></tr>
      <tr><td class="clt_data">connector_util.jar<br>core_util.jar<br>
          etomcat.jar<br>jasper-runtime.jar<br>servlet.jar<br>tomcat_core.jar</td></tr>
	  </table>
	</td>
	<td>&nbsp;</td><td>&nbsp;</td></tr>
  <tr><td>&nbsp;</td><td>&nbsp;</td><td align="center">|</td><td>&nbsp;</td><td>&nbsp;</td></tr>
  <tr><td>&nbsp;</td><td>&nbsp;</td><td>
    <table align="center">
      <tr><td class="clt_loader">Application Classloader</td></tr>
      <tr><td class="clt_data">the CLASSPATH classloader</td></tr>
      <tr><td class="clt_label">default contents:</td></tr>
      <tr><td class="clt_data">tomcat.jar</td></tr>
	</table>
    </td><td>&nbsp;</td><td>&nbsp;</td></tr>
  <tr><td>&nbsp;</td><td>&nbsp;</td><td align="center">|</td><td>&nbsp;</td><td>&nbsp;</td></tr>
  <tr><td>&nbsp;</td><td>&nbsp;</td><td>
    <table align="center">
      <tr><td class="clt_loader">JDK Extensions Classloader</td></tr>
      <tr><td class="clt_label">directory:</td></tr>
      <tr><td class="clt_data"><i>jdk</i>/jre/lib/ext</td></tr>
	  </table></td>
	<td>&nbsp;</td><td>&nbsp;</td></tr>
</table>

<p>In this classloader hierarchy, classloaders can access classes in
classloaders beneath them. They can not access classes in classloaders to the
side or above! To understand why this is important, consider whether web
applications would have access to an XML parser in this classloader hierarchy.
A brief inspection should reveal that in Tomcat 3.3, web applications would
not normally have access to an XML parser. The <code>crimson.jar</code> and
<code>xalan.jar</code> are tucked away in the <b>Server Classloader</b> where
they are accessible only within that classloader.  The same is true for the
other jars in <code>Server Classloader</code> are not visible to web applications
as well.</p>

<p>The primary benefit of this new classloader hierarchy is that you can put
your own XML parser in your web application without running into conflicts with
the XML parser being used by the server.  However, since having an XML parser
by default has been the norm in the past, Tomcat 3.3 tries to maintain this
behavior should your web application not already contain an XML parser.  The
default configuration for the
<a href="serverxml.html#LoaderInterceptor11">LoaderInterceptor11</a> in
<code>server.xml</code> is to provide an XML parser to web applications
that don't already contain one.  It accomplishes this by adding entries to
the <code>Webapp Classloader</code> as if you had included the
<code>crimson.jar</code> and <code>xalan.jar</code> in your web application's
<code>WEB-INF/lib</code>.</p>

<p>Along with this classloader hierarchy comes the need to decide which
classloader is the appropriate one in which to add classes or jars.
Note that if you have a jar containing classes that depend on
<code>servlet.jar</code>, putting that jar on the CLASSPATH wouldn't work.
<code>servlet.jar</code> isn't accessible to the <b>Application Classloader</b>.
This is why in Tomcat 3.3, your CLASSPATH environment variable is ignored.  The
appropriate classloader would be the <b>Common Classloader</b> or above.</p>

<p>Classes that are used in one particular web application should be placed
in that web application's <code>WEB-INF/classes</code> or in a jar in the
<code>WEB-INF/lib</code> as defined by the Servlet 2.2 specification.  If you
want to give the classes wider scope by putting them in the
<code>Common Classloader</code> or <code>Apps Classloader</code>, or want them
to be part of the <code>Server Classloader</code>, use one of the following two
methods to have those classes included in that classloader:

<ol>
  <li>If the classes are in a jar file, place the jar file in the directory
      that corresponds to the chosen classloader.  If the classes exist as
      class files, create a <code>classes</code> under the corresponding
      directory if it doesn't already exist.  Then add the class files into
      the appropriate package directory under the <code>classes</code>
      directory.</li>
  <li>If the chosen classloader is the <code>Common Classloader</code> or
      <code>Apps classloader</code> you include a directory or jar these
      classloaders by listing them a System property. For the
      <code>Common Classloader</code>, include the directory or jar file in a
      System property named <code>org.apache.tomcat.common.classpath</code>.
      For the <code>Apps classloader</code>, use a System property named
      <code>org.apache.tomcat.apps.classpath</code>.</li>
</ol>

<p><b>Note:</b> In an instance of Tomcat 3.3 which is using
<a href="serverxml.html#ReloadInterceptor">ReloadInterceptor</a> (the default),
the <b>Webapp Classloader</b>, <b>Apps Classloader</b>, and <b>Common classloader</b>
are &quot;wrapped&quot; into a single classloader.  This classloader will be an
instance of <code>org.apache.tomcat.util.depend.DependClassLoader</code> or
<code>org.apache.tomcat.util.depend.DependClassLoader12</code>, depending
on which JDK you are using.  This classloader checks for updates when classes
are loaded from the &quot;wrapped&quot; classloaders so that reloads can
be triggered when needed.</p>

<h3><a name="configuring_server">Configuring the Server</a></h3>

<h4><a name="conf_svr_overview"></a>Overview</h4>

<p>By default, Tomcat's configuration is determined by the contents of the
<code>server.xml</code> file found in Tomcat's <code>conf</code> directory.
This file specifies the sequence of <strong>modules</strong> (a.k.a. interceptors)
that should participate in the operation of this instance of Tomcat.  This file
also includes the operating parameters for those modules.</p>

<p>Prior to reading the <code>server.xml</code> file, Tomcat reads the
<code>modules.xml</code> file which is also found in the <code>conf</code>
directory.  This file specifies mappings between module names and the class
that implements the module.  This simplifies the syntax in <code>servers.xml</code>
and allows you to update a module's class by updating just <code>modules.xml</code>.
The <code>server.xml</code>, and possibly other files, do not have to change.</p>

<p>To allow for customization of Tomcat's configuration without requiring
modification of <code>modules.xml</code> and <code>server.xml</code>, Tomcat
will read additional files during startup.  In addition to <code>modules.xml</code>,
Tomcat will read any file in the <code>conf</code> directory that matches the
pattern <code>modules-*.xml</code>.  Likewise for <code>server.xml</code>,
by default Tomcat will read additional files which match the pattern
<code>server-*.xml</code>.</p>

<p>If you specify the configuration file (i.e. the file to use in place of
<code>server.xml</code>) as a command line argument, the additional files read
will be derived from the base name of the file you specify.  For example, if
the configuration file specified was <code>myserver.xml</code>, then the file
pattern would be <code>myserver-*.xml</code>.  Because of this, you should avoid
using '-' in your configuration file names except when taking advantage of this
feature.</p>

<p>When using additional configuration files in conjunction with
<code>server.xml</code> it is important to note that these configuration files
apply to a single Tomcat 3.3 server instance.  In other words, all
&lt;ContextManager&gt; elements in these files refer to the same ContextManager
instance. ContextManager is the controlling class for the Tomcat 3.3 server.</p>

<p>Other files may be read as well for configuration. These, however, are determined
by the <strong>modules</strong> that are included by <code>server.xml</code>
and associated files.  The primary example of this is <code>ContextXmlReader</code>.
It is responsible for reading files containing Context declarations in the form:</p>
<pre>&lt;Context path=&quot;/myapp&quot; docBase=&quot;<i>somepath</i>&quot; ... /&gt;</pre> or 
<pre>&lt;Context path=&quot;/myapp&quot; docBase=&quot;<i>somepath</i>&quot; ...&gt;
    <i>context local modules</i>
&lt;/Context&gt;</pre>

<p>By separating the reading of &quot;context&quot; configurations from the
server configuration, you can manually add additional contexts without
modifying the <code>server.xml</code> file.</p>

<p>The <code>ContextXmlReader</code> module supports a <code>config</code>
parameter which specifies the file to read.  Like <code>server.xml</code>,
additional files are read based on the pattern <code>&lt;base&gt;-*.xml</code>.
Thus, specifying <code>config=&quot;conf/myapps.xml&quot;</code> would read
<code>conf/myapps.xml</code>, if it exists, plus all files in the
<code>conf</code> directory matching the pattern <code>myapps-*.xml</code>.</p>

<p>Tomcat 3.3's default <code>server.xml</code> includes two instances of the
<code>ContextXmlReader</code> module.  One reads <code>conf/apps.xml</code>,
which reads all the &quot;apps&quot; files found in the <code>conf</code>
directory by default.  For backward compatibility with having &quot;context&quot;
declarations in <code>server.xml</code>, the second instance of
<code>ContextXmlReader</code> reads <code>conf/server.xml</code>, processing
only the <code>&lt;Context&gt;</code> entries.</p>

<p>For additional information about contexts and their configuration, see
<a href="#standard_contexts">Tomcat's Standard Contexts</a> and
<a href="#context_addcust">Adding and Customizing Contexts</a>.</p>

<h4><a name="conf_svr_default">Default Tomcat Configuration</a></h4>

<p>The default <code>server.xml</code> contains the following configuration.</p>

<table border="1">
  <tr><th>Module Entry</th><th>Status</th><th>Description</th></tr>
  <tr><td>&lt;<a href="serverxml.html#LoaderInterceptor11">LoaderInterceptor11</a>
    useApplicationLoader=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>Constructs and sets the classloader for each context</td></tr>
  <tr><td>&lt;<a href="serverxml.html#TrustedLoader">TrustedLoader</a> /&gt;</td>
    <td>&nbsp;</td>
    <td>Provides special handling for &quot;trusted&quot; contexts which have
      a <code>interceptors.xml</code> file in their <code>WEB-INF</code>
      directory.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#LogSetter">LogSetter</a>
      name=&quot;tc_log&quot; timestamps=&quot;true&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;verbosityLevel=&quot;INFORMATION&quot;  /&gt;</td><td>&nbsp;</td>
    <td>Sets up Tomcat's log output channel. In the absence of a <code>path</code>
      setting, output goes to <code>stderr</code>.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#LogEvents">LogEvents</a> enabled=&quot;false&quot; /&gt;</td><td>&nbsp;</td>
    <td>When enabled, logs when module methods are called.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#ContextXmlReader">ContextXmlReader</a>
    config=&quot;conf/server.xml&quot; /&gt;</td><td>&nbsp;</td>
    <td>Reads context definitions from the <code>server.xml</code> file for
      backwards compatibility. This may be removed if you don't put
      context definitions in your <code>server.xml</code> file.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#ContextXmlReader">ContextXmlReader</a>
    config=&quot;conf/apps.xml&quot; /&gt;</td><td>&nbsp;</td>
    <td>Reads context definitions from the <code>conf/apps.xml</code> file
      and any files matching the pattern <code>apps-*.xml</code> in the
      <code>conf</code> directory.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#AutoDeploy">AutoDeploy</a>
    source=&quot;modules&quot; target=&quot;modules&quot; 
	redeploy=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>Expands &quot;.war&quot; files in the <code>modules</code> directory.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#AutoWebApp">AutoWebApp</a>
    dir=&quot;modules&quot; host=&quot;DEFAULT&quot; trusted=&quot;true&quot;/&gt;</td><td>&nbsp;</td>
    <td>Auto-creates contexts for subdirectories in the <code>modules</code>
      directory. These contexts are defaulted to &quot;trusted&quot;.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#AutoDeploy">AutoDeploy</a>
    source=&quot;webapps&quot; target=&quot;webapps&quot; /&gt;</td><td>&nbsp;</td>
    <td>Expands &quot;.war&quot; files in the <code>webapps</code> directory.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#AutoWebApp">AutoWebApp</a>
    dir=&quot;webapps&quot; host=&quot;DEFAULT&quot; /&gt;</td><td>&nbsp;</td>
    <td>Auto-creates contexts for the subdirectories in the <code>webapps</code>
      directory.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#PolicyLoader">PolicyLoader</a><br>
	  &nbsp;&nbsp;&nbsp;&nbsp;securityManagerClass=&quot;java.lang.SecurityManager&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;policyFile=&quot;conf/tomcat.policy&quot; /&gt;</td><td>&nbsp;</td>
    <td>Sets a policy file and security manager if &quot;sandbox&quot; is
      specified on the command line without also specifying a policy file
      on the command line.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#SimpleMapper1">SimpleMapper1</a> /&gt;</td><td>&nbsp;</td>
    <td>Handles the mapping of requests to contexts.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#SessionExpirer">SessionExpirer</a>
    checkInterval=&quot;60&quot; /&gt;</td><td>&nbsp;</td>
    <td>Handles the destruction of sessions after they expire.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#SessionIdGenerator">SessionIdGenerator</a><br>
	  &nbsp;&nbsp;&nbsp;&nbsp;randomClass=&quot;java.security.SecureRandom&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;randomFile=&quot;/dev/urandom&quot; /&gt;</td><td>&nbsp;</td>
    <td>Generates session IDs for requests that need a new session.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#LogSetter">LogSetter</a>
      name=&quot;servlet_log&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;timestamps=&quot;true&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;verbosityLevel = &quot;INFORMATION&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;path=&quot;logs/servlet-${yyyyMMdd}.log&quot; 
		   /&gt;</td><td>&nbsp;</td>
    <td>Sets up the &quot;servlet&quot; log output channel.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#LogSetter">LogSetter</a>
      name=&quot;JASPER_LOG&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;timestamps=&quot;true&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;path=&quot;logs/jasper-${yyyyMMdd}.log&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;verbosityLevel = &quot;INFORMATION&quot;  /&gt;</td><td>&nbsp;</td>
    <td>Sets up the Jasper's log output channel.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#WebXmlReader">WebXmlReader</a>
    validate=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>Reads the <code>web.xml</code> file for each context.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#ErrorHandler">ErrorHandler</a>
    showDebugInfo=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>Provides error handling for requests that encounter an error.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#WorkDirSetup">WorkDirSetup</a>
    cleanWorkDir=&quot;false&quot; /&gt;</td><td>&nbsp;</td>
    <td>Sets the &quot;work&quot; directory for contexts which don't have the
      &quot;work&quot; directory set explicitly.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#Jdk12Interceptor">Jdk12Interceptor</a>
    /&gt;</td><td>&nbsp;</td>
    <td>Insures the proper context classloader is in effect during servlet
      execution.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#InvokerInterceptor">InvokerInterceptor</a>
    /&gt;</td><td>&nbsp;</td>
    <td>Handles the &quot;/servlet/<i>class name</i>&quot; legacy method of
      invoking servlets</td></tr>
  <tr><td>&lt;<a href="serverxml.html#JspInterceptor">JspInterceptor</a>
      keepGenerated=&quot;true&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;largeFile=&quot;false&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;useJspServlet=&quot;false&quot; /&gt;</td><td>&nbsp;</td>
    <td>Handles translation, compilation, and loading of JSP pages.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#StaticInterceptor">StaticInterceptor</a>
    listings=&quot;true&quot;<br>
    &nbsp;&nbsp;&nbsp;&nbsp;useAcceptLanguage=&quot;true&quot;<br>
    &nbsp;&nbsp;&nbsp;&nbsp;useCharset=&quot;locale&quot; /&gt;</td><td>&nbsp;</td>
    <td>Generates the response for requests for static files and directories.<br>
      <b>Note:</b> The last two attributes were added in Tomcat 3.3.1 to
      provide improved behavior with the addition of Japanese resource strings.</td></tr>
  <tr><td>&lt;ReloadInterceptor fullReload=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>&nbsp;</td></tr>
  <tr><td>&lt;<a href="serverxml.html#SimpleSessionStore">SimpleSessionStore</a>
    maxActiveSessions=&quot;-1&quot; /&gt;</td><td>&nbsp;</td>
    <td>Creates, stores, and maintains session objects.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#AccessInterceptor">AccessInterceptor</a>
    /&gt;</td><td>&nbsp;</td>
    <td>Checks if requests require authentication. Provides the basic handling
      for BASIC and FORM authentication.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#CredentialsInterceptor">CredentialsInterceptor</a>
    /&gt;</td><td>&nbsp;</td>
    <td>Extracts user name and password information for use by an
      &quot;authentication&quot; module.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#SimpleRealm">SimpleRealm</a>
    filename=&quot;conf/users/global-users.xml&quot; /&gt;</td><td>&nbsp;</td>
    <td>&quot;authentication&quot; module that checks user name and passwords
      against data obtained from an XML file. Since this module appears outside
      of a Context definition, the user names and passwords in the specified
      file apply to all contexts.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#JDBCRealm">JDBCRealm</a><br>
	  &nbsp;&nbsp;&nbsp;&nbsp;debug=&quot;99&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;driverName=&quot;sun.jdbc.odbc.JdbcOdbcDriver&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;connectionURL=&quot;jdbc:odbc:TOMCAT&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;userTable=&quot;users&quot; userNameCol=&quot;user_name&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;userCredCol=&quot;user_pass&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;userRoleTable=&quot;user_roles&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;roleNameCol=&quot;role_name&quot; /&gt;</td><td>Disabled</td>
    <td>A replacement for SimpleRealm that reads usernames, passwords, and roles
      from tables using JDBC.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#LoadOnStartupInterceptor">LoadOnStartupInterceptor</a>
    /&gt;</td><td>&nbsp;</td>
    <td>Pre-loads servlets indicated as &lt;load-on-startup&gt; in a web.xml
      file.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#Servlet22Interceptor">Servlet22Interceptor</a>
    /&gt;</td><td>&nbsp;</td>
    <td>Handles miscellaneous tasks that help implement behavior related to the
      Servlet 2.2 specification.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#LogSetter">LogSetter</a>
     name=&quot;tag_pool_log&quot; timestamps=&quot;true&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;path=&quot;logs/tagpool-${yyyyMMdd}.log&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;verbosityLevel=&quot;INFORMATION&quot; /&gt;</td><td>Disabled</td>
    <td>Sets up the &quot;tag_pool_log&quot; log output channel.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#TagPoolManagerInterceptor">TagPoolManagerInterceptor</a>
    /&gt;</td><td>Disabled</td>
    <td>Manages a pool of custom tag libary tag objects.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#DecodeInterceptor">DecodeInterceptor</a>
    /&gt;</td><td>&nbsp;</td>
    <td>Handles the determination of the encoding of a request.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#SessionId">SessionId</a>
    cookiesFirst=&quot;true&quot; noCookies=&quot;false&quot; /&gt;</td><td>&nbsp;</td>
    <td>Handles associating sessions with requests and responses.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#ApacheConfig">ApacheConfig</a>
    noRoot=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>Generates a configuration file for use with <code>mod_jk</code>.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#IISConfig">IISConfig</a>
    noRoot=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>Generates a configuration file for use with <code>isapi_redirect.dll</code>.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#NSConfig">NSConfig</a>
    noRoot=&quot;true&quot; /&gt;</td><td>&nbsp;</td>
    <td>Generates a configuration file for use with <code>nsapi_redirect</code>.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#AccessLogInterceptor">AccessLogInterceptor</a>
    /&gt;</td><td>Disabled</td>
    <td>Writes a log file like Apache's AccessLog</td></tr>
  <tr><td>&lt;<a href="serverxml.html#Http10Connector">Http10Connector</a> port=&quot;8080&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;secure=&quot;false&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;maxThreads=&quot;100&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;maxSpareThreads=&quot;50&quot;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;minSpareThreads=&quot;10&quot; /&gt;</td><td>&nbsp;</td>
    <td>Handles incoming HTTP requests.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#Http10Connector">Http10Connector</a>
    port=&quot;8443&quot; secure=&quot;true&quot; /&gt;</td><td>Disabled</td>
    <td>Handles incoming HTTPS requests.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#JniConnector">JniConnector</a> /&gt;</td><td>&nbsp;</td>
    <td>Handles requests processed by Tomcat running in-process, provided
      Tomcat was started in-process.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
    port=&quot;8007&quot; /&gt;</td><td>&nbsp;</td>
    <td>Handles Ajp12 protocol requests and Tomcat shutdown.</td></tr>
  <tr><td>&lt;<a href="serverxml.html#Ajp13Connector">Ajp13Connector</a>
    port=&quot;8009&quot; /&gt;</td><td>&nbsp;</td>
    <td>Handles Ajp13 protocol requests.</td></tr>
</table>

<h4><a name="conf_svr_cust">Tomcat Server.xml Customization</a></h4>

<p>The following are some of the more common customizations made to the
<code>server.xml</code> file.</p>

<ol>
<li><a href="#cust_chgports">Change ports for Http, Https, and Web Server connectors</a></li>
<li><a href="#cust_session">Speed up initial session creation for development</a></li>
<li><a href="#cust_auth">Configure whether Tomcat or a web server does authentication</a></li>
<li><a href="#cust_dirlist">Turn off directory listings</li>
<li><a href="#cust_jikes">Use Jikes as the Java compiler</a></li>
<li><a href="#cust_bind">Bind a connector to a single IP address</a></li>
<li><a href="#cust_redeploy">Enable redeploying of WAR files</a></li>
<li><a href="#cust_session">Disable cookie based sessions</a></li>
</ol>

<hr>

<p>1. <a name="cust_chgports">Change ports for Http or Web Server connectors</a></p>

<p>To change a port, search the <code>server.xml</code> file for the default
value of the port and change it to the desired value.</p>

<table border="1">
  <tr><th>Connector</th><th>Default Port</th></tr>
  <tr><td>Http</td><td>8080</td></tr>
  <tr><td>Https</td><td>8443</td></tr>
  <tr><td>Ajp12Connector</td><td>8007</td></tr>
  <tr><td>Ajp13Connector</td><td>8009</td></tr>
</table>
<p>For example:</p>
<pre>
    &lt;Http10Connector port=&quot;80&quot; secure=&quot;false&quot;
        maxThreads=&quot;100&quot; maxSpareThreads=&quot;50&quot; minSpareThreads=&quot;10&quot; /&gt;
</pre>

<hr>

<p>2. <a name="cust_session">Speed up initial session creation for development</a></p>

<p>The first request that requires a session can incur a delay when the
<a href="serverxml.html#SessionIdGenerator">SessionIdGenerator</a> initializes
the random number generator.  This delay can be relatively long when using
the default <code>java.security.SecureRandom</code> class.  For development
purposes, you can speed this up by switching to the <code>java.util.Random</code>
class. For example:</p>
<pre>
    &lt;SessionIdGenerator randomClass=&quot;java.util.Random&quot; randomFile=&quot;/dev/urandom&quot; /&gt;
</pre>
<p>You should only use <code>java.util.Random</code> for development
since the random sequence generated is predictable.</p>

<hr>

<p>3. <a name="cust_auth">Configure whether Tomcat or a web server does authentication</a></p>

<p>When Tomcat is used with a web server, such as Apache, the default is to have
Tomcat continue to handle authentication.  Any authenticated user specified in
the request forwarded from the web server to Tomcat will be ignored.</p>

<p>If you want Tomcat to make use of the authenticated user provided by
the web server, add:</p>
<pre>
    tomcatAuthentication=&quot;false&quot;
</pre>
<p>to the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a> or
<a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> as appropriate.
For example:</p>
<pre>
    &lt;Ajp13Connector port=&quot;8009&quot; tomcatAuthentication=&quot;false&quot; /&gt;
</pre>

<hr>

<p>4. <a name="cust_dirlist">Turn off directory listings</a></p>

<p>To turn off directory listings, change the <code>listings</code> attribute of
the <a href="serverxml.html#StaticInterceptor">StaticInterceptor</a> to
<code>false</code>.  For example:</p>
<pre>
    &lt;StaticInterceptor listings=&quot;false&quot; /&gt;
</pre>

<hr>

<p>5. <a name="cust_jikes">Use Jikes as the Java compiler</a></p>

<p>To have Tomcat use Jikes as the Java compiler, add:</p>
<pre>
    javaCompiler=&quot;jikes&quot;
</pre>
<p>to the <a href="serverxml.html#JspInterceptor">JspInterceptor</a>. For example:</p>
<pre>
    &lt;JspInterceptor javaCompiler=&quot;jikes&quot; /&gt;
</pre>

<p>You may want to also set the <code>jikesClasspath</code> attribute to
include any jars from the <code>jre/lib/ext</code> extensions directory, or any
classes or jars not otherwise found in the <code>WEB-INF/classes</code> and
<code>WEB-INF/lib</code> directories.</p>

<p>If the Jikes executable isn't in your <code>PATH</code> environment
variable, you will also need to set the <code>jspCompilerPath</code> attribute
to the full path of the Jikes executable.</p>
<hr>

<p>6. <a name="cust_bind">Bind a connector to a single IP address</a></p>

<p>By default, the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
and <a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> will accept
connections from any IP address.  To bind the connector to a single IP address,
add an <code>address</code> attribute specifying the desired IP address.
For example:</p>
<pre>
    &lt;Ajp13Connector port=&quot;8009&quot; address=&quot;127.0.0.1&quot; /&gt;
</pre>

<hr>

<p>7. <a name="cust_redeploy">Enable redeploying of WAR files</a></p>

<p>The default behavior is to only deploy a WAR file if the target directory
doesn't already exists.  To enable automatic redeployment of WAR files, add:</p>
<pre>
    redeploy=&quot;true&quot;
</pre>
<p>to the <a href="serverxml.html#AutoDeploy">AutoDeploy</a> with
<code>source=&quot;webapps&quot;</code>. In addition to re-deploying WAR files
at startup, because a <a href="serverxml.html#ReloadInterceptor">ReloadInterceptor</a>
is part of the default configuration, WAR files will re-deploy and reload if
updated while Tomcat is running.</p>

<hr>

<p>8. <a name="cust_session">Disable cookie based sessions</a></p>

<p>To assist with testing a web application against browsers that have
cookies disabled, you can disable the use of cookie bases sessions.  Change the
<code>noCookies</code> attribute of the <a href="serverxml.html#SessionId">SessionId</a>
module to <code>true</code>.  For example:</p>
<pre>
    &lt;SessionId cookiesFirst=&quot;true&quot; noCookies=&quot;true&quot; /&gt;
</pre>

<hr>

<h4><a name="standard_contexts">Tomcat's Standard Contexts</a></h4>

<p>A context is an instance of a web application's resources being served
with a unique context path.  The default Tomcat 3.3 installation comes with
three web applications which are served as the following contexts.</p>

<table border="1">
  <tr><th>Context</th><th>path</th><th>docBase</th><th>WAR File</th><th>Context Config File</th></tr>
  <tr><td><i>default</i></td><td><i>empty</i>, i.e. &quot;&quot;</td>
      <td>webapps/ROOT</td><td>ROOT.war</td><td>&nbsp;</td></tr>
  <tr><td>admin</td><td>/admin</td><td>webapps/admin</td><td>admin.war</td>
      <td>apps-admin.xml</td></tr>
  <tr><td>examples</td><td>/examples</td><td>webapps/examples</td>
      <td>examples.war</td><td>apps-example.xml</td></tr>
</table>

<p>The <i>default</i> context is the context that will handle requests that
don't match up with any of the other contexts being served.</p>

<p>Each of these contexts have their WAR file auto-deployed by the
<a href="serverxml.html#AutoDeploy">AutoDeploy</a> module and the deployed
directory auto-served by the <a href="serverxml.html#AutoWebApp">AutoWebApp</a>
module.  The <code>apps-admin.xml</code> and <code>apps-example.xml</code>
files found in the <code>conf</code> directory provide additional configuration
for the <code>admin</code> and <code>examples</code> contexts, respectively.
Both configuration files add a local <a href="serverxml.html#SimpleRealm">SimpleRealm</a>
module which defines additional users that may use the secure portions of
those contexts. The <code>apps-example.xml</code> also configures local log
channels for the internal context log and the servlet log.</p>

<p>For the <code>admin</code> context to function properly, you will need
to update the <code>apps-admin.xml</code> file to set the context's
<code>trusted</code> attribute to <code>true</code>.  You can do this from
the command line using the &quot;tomcat&quot; script/batch file and the
<code>enableAdmin</code> action (see
<a href="#tomcat_actions">tomcat/tomcat.bat Actions</a> for details).
The <code>trusted</code> attribute is set <code>false</code> by default for
security reasons.  When you change it to <code>true</code>, it is also
recommended that you change the password in the
<code>conf/users/admin-users.xml</code> file.</p>

<p>There is an additional context configuration file, named
<code>apps-127.0.0.1.xml</code>. This file contains a <b>disabled</b> example
of defining contexts that are associated with a virtual host. In this case, a
host with a name that matches it's IP address, 127.0.0.1. To enable, uncomment
the <code>Host</code> element in this file.</p>

<p>Tomcat 3.3 first tries to match a request to a context that has a virtual
host name that matches the server name in the request.  If unable to do so,
the request will be matched to one of the other contexts, which don't have a
virtual host associated.  Note that this means that contexts associated with a
virtual host are separate from other contexts not associated with a virtual
host.</p>

<p>In this virtual host example, the <code><i>default</i></code> and
<code>examples</code> contexts are swapped. Thus, the URL
<a href="http://127.0.0.1:8080/examples/">http://127.0.0.1:8080/examples/</a>
will show you the Tomcat main page instead of the examples directory.  The
URL <a href="http://localhost:8080/examples/">http://localhost:8080/</a>
would be the normal way to reach the Tomcat main page. To illustrate that
a context associated with a virtual host is a separate context, you can
invoke <a href="http://127.0.0.1:8080/jsp/security/protected/index.jsp">
http://127.0.0.1:8080/jsp/security/protected/index.jsp</a> in your browser.
Since this, <i>default</i>, context is serving the &quot;examples&quot; web
application, but without an additional <a href="serverxml.html#SimpleRealm">SimpleRealm</a>
defined, only the &quot;global user&quot; <code>root</code> (defined by
the SimpleRealm in <code>server.xml</code>) can login.</p>

<h4><a name="context_addcust">Adding and Customizing Contexts</a></h4>

<p>To serve a context, Tomcat 3.3 requires a directory that contains the
resources for the context. This directory must match the structure and
requirements defined for a web application.  Once this directory exists,
it may be served as a context using one or both of the following mechanisms.</p>

<ol>
  <li>Specify the context in a context configuration file read by a
      <a href="serverxml.html#ContextXmlReader">ContextXmlReader</a> module.
      This module will read a specified context configuration file, if it
      exists, and all files with an associated pattern.  The default Tomcat 3.3
      installation has a ContextXmlReader that reads the "apps.xml" file.
      Though this file doesn't exist, the associated pattern is
      <code>&quot;apps-*.xml&quot;</code> which picks up the
      <code>apps-admin.xml</code>, <code>apps-example.xml</code>, and
      <code>apps-127.0.0.1</code>.  You can create an <code>apps.xml</code>
      or <code>apps-myapps.xml</code> file, for example, to add your own context
      definitions.<br><br></li>
  <li>If the context's directory is a subdirectory of an directory
      named in an <a href="serverxml.html#AutoWebApp">AutoWebApp</a> module,
      it will be served using the context's directory name as the context path.
      The default installation of Tomcat 3.3 has one such AutoWebApp module
      which serves subdirectories of Tomcat's <code>webapps</code> directory.
      The contexts served in this manner will receive the default context
      settings unless overridden by a context configuration file for that
      context.<br>
      <br>
      <b>Note:</b> The AutoWebApp module which serves the <code>modules</code>
      directory is reserved for Tomcat Add-on modules and should not be used
      for serving contexts.</li>
</ol>

<p>The format of context configuration files differs depending on whether
the context is for the default host or a virtual host.  For contexts not
associated with a virtual host, use:</p>

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt;
&lt;webapps&gt;
    &lt;Context ... &gt;
        &lt;<i>local_module</i> ... /&gt;
        ...
    &lt;/Context&gt;
    ...
&lt;/webapps&gt;
</pre>

<p>For contexts that are to be associated with virtual hosts, use:</p>

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt;
&lt;Server&gt;
    &lt;Host ... &gt;
        &lt;Alias ... /&gt;
        &lt;Context ... &gt;
            &lt;<i>local_module</i> ... /&gt;
            ...
        &lt;/Context&gt;
        ...
    &lt;/Host&gt;
    ...
&lt;/Server&gt;
</pre>

<p>The following table provides the attributes available on these elements.</p>

<table border="1">
  <tr valign="top"><th>Element</th><th>Attribute</th><th>Description</th><th>Default</th></tr>
  <tr valign="top"><td>Context</td><td>path</td>
      <td>The URL fragment to use to identify this context. This is a required
          attribute.</td>
      <td><i>none, must be specified</i></td></tr>
  <tr valign="top"><td>&nbsp;</td><td>docBase</td>
      <td>Path to the directory containing the web application's resources for
      the context. This is a required attribute.</td>
      <td><i>none, must be specified</i></td></tr>
  <tr valign="top"><td>&nbsp;</td><td>reloadable</td><td>Enables reloading of
      servlets for this context.</td><td>true</td></tr>
  <tr valign="top"><td>&nbsp;</td><td>trusted</td><td>Controls whether the
      context is &quot;trusted&quot;.  If &quot;trusted&quot;, the
      <code>Webapp Classloader's</code> parent will be the
      <code>Server Classloader</code> rather than the <code>Apps Classloader</code>.
      This gives the context access to classes in the Tomcat server instance.
      </td><td>false</td></tr>
  <tr valign="top"><td>&nbsp;</td><td>debug</td><td>Debug level for logging</td><td>0</td></tr>
  <tr valign="top"><td>Host</td><td>name</td><td>Name of the virtual host. This is a
      required attribute.</td>
      <td><i>none, must be specified</i></td></tr>
  <tr valign="top"><td>&nbsp;</td><td>address</td><td>IP address for this virtual host. This
      attribute is optional.  Currently, this attribute only affects how the
      <a href="serverxml.html#ApacheConfig">ApacheConfig</a> module writes the
      configuration file.</td>
      <td><i>none, must be specified.</i></td></tr>
  <tr valign="top"><td>Alias</td><td>name</td><td>Name of the virtual host alias.<br>
      <b>Note:</b> All <code>Alias</code> specifications must come before any
      <code>Context</code> declarations.</td><td><i>none, must be specified</i></td></tr>
</table>

<p>In Tomcat 3.3.1, each attribute value may use the ant-style variable
substitution by using &quot;${<i>variable</i>}&quot; in the attribute string, i.e.
<i>attribute</i>=&quot;<i>text</i>${<i>variable</i>}<i>text</i>&quot;.</p>

<p>The <i>variable</i> must specify a Context property, a ContextManager
property, or System property.  The Context properties take precedence, followed
by ContextManager propertiers, and finally System properties.  If a matching
property isn't found, the attribute string is left as is.  Note that properties
are not the same as attributes, and attributes are not accessible via
&quot;variable substitution&quot;.</p>

<p><a name="context_prop"></a>There are two methods for setting Context properties.</p>

<ol>
  <li>Include a <code><i>name</i>=&quot;<i>value</i>&quot;</code>
    specification on the Context element, where <i>name</i> doesn't correspond
    to a Context attribute. For example:<br>
    <pre>    &lt;Context ... my.prop="myvalue" ... &gt;</pre></li>
  <li>Include a <code>Property</code> element within the scope of the
    Context element. For example:<br>
    <pre>
    &lt;Context ... &gt;
        &lt;Property name=&quot;my.prop&quot; value=&quot;myvalue&quot; /&gt;
        ...
    &lt;/Context&gt;</pre>
    This form of setting properties is logged if the Context's debug
    level is one or greater.<br><br></li>
</ol>

<p><b>Note:</b> The property values may themselves use &quot;variable
substitution&quot;, provided the specified property is already defined.</p>

<p>Currently the <a href="serverxml.html#SimpleRealm">SimpleRealm</a>,
<a href="serverxml.html#JDBCRealm">JDBCRealm</a>, and
<a href="serverxml.html#LogSetter">Logsetter</a> modules are known to work
successfully as &quot;context local&quot; modules.  Other modules that can
be used as &quot;context local&quot; modules and would be useful have yet to
be identified.</p>

<p>To add, or remove, a context while Tomcat 3.3 is running, use the Admin
web application provided in the <code>admin</code> context.  Note that the
<code>admin</code> context must be &quot;trusted&quot; before it can perform
the admin functions successfully.</p>

<h4><a name="deploy_war">Deploying WAR Files</a></h4>

<p>The Servlet 2.2 specification introduced the Web Application Archive, or WAR
file. A WAR file is the deployable version of a web application, where the
directory structure and the files they contain are combined into an archive file.</p>

<p>To deploy a WAR file to Tomcat 3.3, you can manually expand the archive to a
directory and have that directory served as a context as described above. You
can also have the <a href="serverxml.html#AutoDeploy">AutoDeploy</a> module
do the expansion automatically if the WAR file is placed in its &quot;source&quot;
directory.  The default installation of Tomcat 3.3 includes an AutoDeploy
module which expands WAR files found in Tomcat's <code>webapps</code>
directory.</p>

<p>To add a WAR file while Tomcat 3.3 is running, you will need to manually
expand the WAR file.  Then use the Admin web application to add the 
context.</p>

<hr size="5">

<h2><a name="real_world_tips">Real World Configuration Tips</a></h2>

<p>By default the Tomcat distribution comes with a naive
	configuration whose main goal is to promote first time
	user experience and an &quot;out of the box&quot; operation...
	This configuration however is not the best way to deploy
	Tomcat on real sites. For example, real sites may
	require some performance tuning and site-specific
	settings (additional path elements for example). This
	section will try to get you started by directing you to
	the first steps that should be taken before publishing a
	Tomcat based site.</p>

<h3>Modify and Customize the Batch Files</h3>

<p>As stated in the previous sections, the startup scripts are
	here for your convenience.  Yet, sometimes the scripts
	that are needed for deployment should be modified:</p>

<ul>
            <li> To set resource limits such as maximum number of
                 descriptors. </li>
            <li> To add new PATH/LD_LIBRARY_PATH entries (for example, JDBC
                 drivers DLLs). </li>
            <li> To modify the JVM command line settings. </li>
            <li> Make sure that you are using a specific JVM (out of the two
                 or three JVMs installed on your machine). </li>
            <li> To switch user from root to some other user using the &quot;su&quot;
                 UNIX command. </li>
            <li> Your pet reason. </li>
</ul>

<p>Some of these changes can be done without explicit changes to
	the basic scripts; for example, the tomcat script can
	use an environment variable named <tt>TOMCAT_OPTS</tt>
	to set extra command line parameters to the JVM (such as
	memory setting etc.). On <em>UNIX</em> you can also
	create a file named <tt>&quot;.tomcatrc&quot;</tt> in your home
	directory and Tomcat will take environment information
	such as PATH, JAVA_HOME, TOMCAT_HOME and TOMCAT_INSTALL from
	this file. On NT however (and also on UNIX when the
	modifications are for something such as the JVM command
	line) you are forced to rewrite some of the startup
	script...</p>

<div><strong>Do not hesitate, just do it.</strong></div>

<h3>Modify the Default JVM Settings</h3>

<p>The default JVM settings in the tomcat script are very
	na&iuml;ve; everything is left for defaults. There are a
	few things that you should consider to improve your
	Tomcat performance:</p>

        <ol>
            <li> Modify your JVM memory configuration. Normally the JVM
           allocates an initial size for the Java heap and that's it, if
           you need more then this amount of memory you will not get it.<br>
           Nevertheless, in loaded sites, giving more memory to the JVM
           improves Tomcat's performance. You should use command line
           parameters such as -Xms/-Xmx/-ms/-mx to set the minimum/maximum
           size of the Java heap (and check to see if the performance was
           improved). </li>

            <li> Modify your JVM threading configuration. The SUN JDK1.2.2 for
           Linux comes with support for both, green and native threads. In
           general native threads are known to provide improved performance
           for I/O bound applications, green threads on the other hand put
           less stress on the machine. You should experiment with these two
           threading models and see which model is better for your site (in
           general, native threads are better).</li>

            <li> Select the best JVM for the task. If your application
           does not require a specific JDK functionality, you should
           benchmark the two JVMs and select the better one.</li>
        </ol>

<h3>Disable Servlet Auto-Reloading</h3>

    <p>
        Servlet auto-reloading is really useful for development time.
        However it is very expensive (in performance degradation terms) and
        may put your application in strange conflicts when classes that were
        loaded by a certain classloader cannot cooperate with classes
        loaded by the current classloader.
    </p>
    <p>
        So, unless you have a real need for class reloading during your
        deployment you should turn off the reloadable flag in your contexts.
        You can disable reloading globally by removing the
        <a href="serverxml.html#ReloadInterceptor">ReloaderInterceptor</a>
        found in the <code>server.xml</code> file.
    </p>

<h3>Start Tomcat from /etc/inittab</h3>

    <p>
        Unfortunately the adapters developed for Apache (or for any of the
        other servers) cannot start Tomcat yet. On UNIX however, you can
        use the init table to start Tomcat automatically upon machine
        startup.
    </p>

<h2><a name="credits">Credits</a></h2>

<p>Tomcat was originally written by Sun Microsystems, and has been improved
(we hope) by a <a href="http://jakarta.apache.org/site/whoweare.html">cast of thousands</a>.</p>

<p>This document was created by:</p>

<ul>
	<li><a href="mailto:shachor@il.ibm.com">Gal Shachor</a>
</ul>

<p>With help from (in alphabetical order):</p>

<ul>
	<li>Jonathan Bnayahu</li>
	<li>Alex Chaffee</li>
	<li>Fiona Czuczman</li>
    <li>Larry Isaacs</li>
	<li>Costin Manolache</li>
	<li>Rob Slifka</li>
</ul>

<table width="100%" border="0" cellpadding="10" cellspacing="0">
      <tr>
        <td>
          <p class="fineprint">
            Copyright &copy;1999-2001 The Apache Software Foundation<br>
            <a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make Us Say</a><br>
            <a href="http://jakarta.apache.org/contact.html">Contact Information</a>
          </p>
        </td>
      </tr>
</table>

</body>
</html>
